========================================
VOUCHER SETTINGS - FLOW DIAGRAM
========================================

┌─────────────────────────────────────────────────────────────┐
│                    SYSTEM ARCHITECTURE                       │
└─────────────────────────────────────────────────────────────┘

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Admin      │      │    Agent     │      │  MikroTik    │
│   Panel      │      │   Panel      │      │   Router     │
└──────┬───────┘      └──────┬───────┘      └──────┬───────┘
       │                     │                     │
       │                     │                     │
       ▼                     ▼                     ▼
┌──────────────────────────────────────────────────────────────┐
│                      WEB APPLICATION                          │
│  ┌────────────┐  ┌────────────┐  ┌────────────────────────┐ │
│  │  Settings  │  │    API     │  │  VoucherGenerator      │ │
│  │   Page     │  │  Generate  │  │       Class            │ │
│  └─────┬──────┘  └─────┬──────┘  └──────────┬─────────────┘ │
│        │               │                    │               │
│        └───────────────┴────────────────────┘               │
│                        │                                    │
└────────────────────────┼────────────────────────────────────┘
                         │
                         ▼
                  ┌─────────────┐
                  │  Database   │
                  │  MySQL      │
                  └─────────────┘


========================================
CONFIGURATION FLOW
========================================

ADMIN SETS VOUCHER FORMAT:

1. Admin Login
   │
   ▼
2. Navigate to Menu
   │
   ├─► Agent/Reseller
   │   │
   │   └─► Format Voucher
   │
   ▼
3. Configure Settings
   │
   ├─► Username & Password (Same/Different)
   ├─► Character Type (Numeric/Alpha/Alphanumeric)
   ├─► Length (4-20 characters)
   ├─► Prefix (Enable/Disable)
   └─► Case (Uppercase/Lowercase)
   │
   ▼
4. Preview Real-time
   │
   ├─► See example voucher
   └─► Adjust if needed
   │
   ▼
5. Save Settings
   │
   └─► Store in database (agent_settings table)


========================================
VOUCHER GENERATION FLOW
========================================

AGENT GENERATES VOUCHER:

1. Agent Login
   │
   ▼
2. Access Dashboard
   │
   ▼
3. Select Profile
   │
   ├─► Choose voucher profile
   └─► Set quantity
   │
   ▼
4. Click Generate
   │
   └─► Send request to API
   │
   ▼
5. API Processing
   │
   ├─► Verify agent authentication
   ├─► Check agent balance
   ├─► Get agent price for profile
   └─► Calculate total cost
   │
   ▼
6. VoucherGenerator Class
   │
   ├─► Load settings from database
   ├─► Generate username based on settings
   │   │
   │   ├─► Get character type
   │   ├─► Get length
   │   ├─► Add prefix (if enabled)
   │   └─► Apply case (upper/lower)
   │
   ├─► Generate password based on settings
   │   │
   │   ├─► Check if same as username
   │   ├─► Get character type
   │   ├─► Get length
   │   └─► Apply case (upper/lower)
   │
   └─► Return voucher data
   │
   ▼
7. Create User in MikroTik
   │
   ├─► Connect to RouterOS API
   ├─► Add hotspot user
   │   │
   │   ├─► Username: [generated]
   │   ├─► Password: [generated]
   │   ├─► Profile: [selected]
   │   └─► Comment: Agent-[code]-[date]
   │
   └─► Disconnect
   │
   ▼
8. Deduct Agent Balance
   │
   ├─► Get current balance
   ├─► Calculate new balance
   ├─► Update agent balance
   └─► Record transaction
   │
   ▼
9. Save Voucher Record
   │
   ├─► Insert to agent_vouchers table
   │   │
   │   ├─► agent_id
   │   ├─► transaction_id
   │   ├─► username
   │   ├─► password
   │   ├─► profile_name
   │   ├─► buy_price
   │   ├─► sell_price
   │   └─► status: active
   │
   └─► Return success response
   │
   ▼
10. Display Result
    │
    ├─► Show generated vouchers
    ├─► Update balance display
    └─► Add to transaction history


========================================
DATA FLOW DIAGRAM
========================================

┌─────────────────────────────────────────────────────────────┐
│                    SETTINGS STORAGE                          │
└─────────────────────────────────────────────────────────────┘

Admin Input
    │
    ▼
┌─────────────────────────────────────┐
│     voucher_settings.php            │
│  ┌───────────────────────────────┐  │
│  │  Form with validation         │  │
│  │  - Username/Password same?    │  │
│  │  - Character type             │  │
│  │  - Length                     │  │
│  │  - Prefix                     │  │
│  │  - Case                       │  │
│  └───────────────────────────────┘  │
└──────────────┬──────────────────────┘
               │
               ▼
        [Save to Database]
               │
               ▼
┌──────────────────────────────────────┐
│      agent_settings table            │
│  ┌────────────────────────────────┐  │
│  │ voucher_username_password_same │  │
│  │ voucher_username_type          │  │
│  │ voucher_username_length        │  │
│  │ voucher_password_type          │  │
│  │ voucher_password_length        │  │
│  │ voucher_prefix_enabled         │  │
│  │ voucher_prefix                 │  │
│  │ voucher_uppercase              │  │
│  └────────────────────────────────┘  │
└──────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────┐
│                  VOUCHER GENERATION                          │
└─────────────────────────────────────────────────────────────┘

Agent Request
    │
    ▼
┌─────────────────────────────────────┐
│  agent_generate_voucher.php (API)   │
│  ┌───────────────────────────────┐  │
│  │  1. Authenticate agent        │  │
│  │  2. Validate parameters       │  │
│  │  3. Check balance             │  │
│  └───────────────────────────────┘  │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    VoucherGenerator.class.php       │
│  ┌───────────────────────────────┐  │
│  │  1. Load settings             │  │
│  │  2. Generate username         │  │
│  │  3. Generate password         │  │
│  │  4. Return voucher data       │  │
│  └───────────────────────────────┘  │
└──────────────┬──────────────────────┘
               │
               ▼
        [Create in MikroTik]
               │
               ▼
┌─────────────────────────────────────┐
│      RouterOS API                   │
│  ┌───────────────────────────────┐  │
│  │  /ip/hotspot/user/add         │  │
│  │  - name: [username]           │  │
│  │  - password: [password]       │  │
│  │  - profile: [profile]         │  │
│  │  - comment: [agent-code]      │  │
│  └───────────────────────────────┘  │
└──────────────┬──────────────────────┘
               │
               ▼
        [Save to Database]
               │
               ▼
┌─────────────────────────────────────┐
│    agent_vouchers table             │
│  ┌───────────────────────────────┐  │
│  │  - agent_id                   │  │
│  │  - username                   │  │
│  │  - password                   │  │
│  │  - profile_name               │  │
│  │  - buy_price                  │  │
│  │  - sell_price                 │  │
│  │  - status: active             │  │
│  └───────────────────────────────┘  │
└──────────────┬──────────────────────┘
               │
               ▼
        [Return to Agent]


========================================
CLASS STRUCTURE
========================================

VoucherGenerator
│
├── Properties
│   ├── $db (PDO connection)
│   └── $settings (array)
│
├── Constructor
│   ├── Connect to database
│   └── Load settings
│
├── Private Methods
│   ├── loadSettings()
│   │   └── Query agent_settings table
│   │
│   └── generateRandomString($type, $length)
│       ├── numeric: 0-9
│       ├── alpha: A-Z
│       └── alphanumeric: 0-9, A-Z
│
└── Public Methods
    ├── generateUsername()
    │   ├── Get type & length from settings
    │   ├── Generate random string
    │   ├── Add prefix (if enabled)
    │   └── Apply case (upper/lower)
    │
    ├── generatePassword($username)
    │   ├── Check if same as username
    │   ├── Get type & length from settings
    │   ├── Generate random string
    │   └── Apply case (upper/lower)
    │
    ├── generateVoucher()
    │   ├── Call generateUsername()
    │   ├── Call generatePassword()
    │   └── Return array [username, password]
    │
    ├── generateMultipleVouchers($quantity)
    │   ├── Loop $quantity times
    │   ├── Call generateVoucher()
    │   ├── Check for duplicates
    │   └── Return array of vouchers
    │
    ├── getSettings()
    │   └── Return all settings
    │
    └── getSetting($key, $default)
        └── Return specific setting


========================================
DATABASE SCHEMA
========================================

agent_settings
├── id (INT, PK, AUTO_INCREMENT)
├── setting_key (VARCHAR, UNIQUE)
├── setting_value (TEXT)
├── setting_type (VARCHAR)
├── description (TEXT)
├── updated_at (TIMESTAMP)
└── updated_by (VARCHAR)

Voucher Settings Keys:
├── voucher_username_password_same
├── voucher_username_type
├── voucher_username_length
├── voucher_password_type
├── voucher_password_length
├── voucher_prefix_enabled
├── voucher_prefix
└── voucher_uppercase


agent_vouchers
├── id (INT, PK, AUTO_INCREMENT)
├── agent_id (INT, FK)
├── transaction_id (INT, FK)
├── username (VARCHAR)
├── password (VARCHAR)
├── profile_name (VARCHAR)
├── buy_price (DECIMAL)
├── sell_price (DECIMAL)
├── status (ENUM: active, used, expired)
├── customer_phone (VARCHAR)
├── customer_name (VARCHAR)
├── sent_via (ENUM: web, whatsapp, manual)
├── created_at (TIMESTAMP)
└── notes (TEXT)


========================================
SECURITY FLOW
========================================

1. Authentication
   │
   ├─► Admin: Session-based
   └─► Agent: Token-based (md5)
   │
   ▼
2. Authorization
   │
   ├─► Check user role
   └─► Verify permissions
   │
   ▼
3. Input Validation
   │
   ├─► Sanitize inputs
   ├─► Validate data types
   └─► Check ranges
   │
   ▼
4. Database Security
   │
   ├─► Prepared statements
   ├─► PDO with error handling
   └─► Transaction support
   │
   ▼
5. Output Encoding
   │
   ├─► HTML escape
   └─► JSON encode


========================================
ERROR HANDLING FLOW
========================================

Try
│
├─► Database Connection
│   ├─► Success → Continue
│   └─► Fail → Log error, show message
│
├─► Settings Load
│   ├─► Success → Continue
│   └─► Fail → Use defaults
│
├─► Voucher Generation
│   ├─► Success → Continue
│   └─► Fail → Retry or error
│
├─► MikroTik Connection
│   ├─► Success → Continue
│   └─► Fail → Rollback, show error
│
└─► Balance Deduction
    ├─► Success → Continue
    └─► Fail → Rollback, show error

Catch
│
└─► Log error
    ├─► Error log file
    ├─► Database log
    └─► Display user-friendly message


========================================
END OF FLOW DIAGRAM
========================================
